@celljs/ta-extensions 4.8.0 → 4.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.en.md CHANGED
@@ -9,6 +9,9 @@ A built-in pi package for Ta (enabled by default, can be disabled in Settings
9
9
  - "Installed Extensions": packages from the `packages` setting (npm or Git), with toggles. You can copy the source or remove them.
10
10
  - Import: use the button, the page's top-right menu, or drag files to the page. In the dialog, select a `.tgz` file or enter an `npm:…` / Git address to install (`installPackage`, equivalent to `ta install`). After import, install, or remove, call `reloadExtensions` so the current session and page get the updates immediately.
11
11
  - "Share with Others": export → send .tgz file → they import. A three-step diagram shows this flow, with a note explaining that npm, Git sources, or telling Ta directly also work.
12
+ - Each row and the page of a package of the marketplace have Share: the share dialog of Ta (a QR code, a link).
13
+ - The search of Quick open gets three sections from here (`search.ts`, `registerSearch`): Installed and Come with Ta, filtered in memory, and Marketplace, npm searched through the host a page at a time, with Install on those not installed.
14
+ - Extensions opened without installing are not listed under "Mine": Quick open installs or deletes them ([@celljs/ta-launcher](../ta-launcher/README.en.md)). The page of a package of the marketplace with a web extension has Open besides Install: its pages run at once as a temporary extension (`pi.openTemporary`), found in Quick open afterwards.
12
15
  - "Marketplace" (`market-view.tsx`, `market-detail.tsx`): npm packages with the `pi-package` keyword—the ones listed in pi's official package directory.
13
16
  - Search box (searches 300 ms after input stops) and a few popular topics. Without keywords, lists by npm's combined ranking (download volume dominates); scrolling to the bottom auto-loads the next page.
14
17
  - Each card shows an avatar from the first letter of the name (same name, same color), name (scope faded), author, monthly downloads, description, category tags, and publish date, with an "Install" button on the right: one-click install as user-level `npm:<name>` (`installPackage`, unpinned version, updatable with `ta update`). A loading spinner appears during install; "Installed" shows when done; built-in extensions show "Built-in". Installation continues if you leave the page.
@@ -24,4 +27,4 @@ A built-in pi package for Ta (enabled by default, can be disabled in Settings
24
27
  - Extensions imported from files are placed only in the user's `extensions/`. To use one in a project, place the directory in the project's `.ta/extensions/` and commit it.
25
28
  - Extensions run code on this machine. Before importing extensions from others, the page warns to only import from trusted sources, and the skill asks Ta to review it first and explain what it does. Marketplace installs are one-click (no approval prompts, following pi's practice); you can view the intro and source code at the bottom of the list or in the detail page.
26
29
  - The marketplace only recognizes the official npm registry (search, manifests, and download counts at registry.npmjs.org). READMEs depend on jsDelivr or GitHub. If either is unreachable, the page shows why and offers "Retry"; this doesn't affect already-installed extensions. Installation still uses pi's npm, respecting your npm config.
27
- - Most npm data is in English; Chinese searches won't find everything. Topic buttons use English keywords.
30
+ - Most npm data is in English; Chinese searches won't find everything. Topic buttons use English keywords.
package/README.md CHANGED
@@ -12,7 +12,10 @@ Ta 自带的 pi 包(默认开启,可在 设置 → 扩展 关闭):告诉
12
12
  - "市场"(`market-view.tsx`、`market-detail.tsx`):npm 上带 `pi-package` 关键词的包,也就是 pi 官网包目录收录的那些。
13
13
  - 搜索框(输入停 300 ms 后搜索)和几个常用话题;没有关键词时按 npm 的综合排序(下载量占大头)列出,滚动到底自动加载下一页。
14
14
  - 每张卡片是名字首字母头像(同名同色)、名称(scope 变淡)、作者、月下载量、说明、类别标签和发布时间,右侧一个"安装"按钮:一键安装为用户级的 `npm:<名字>`(`installPackage`,不锁版本,`ta update` 能更新),安装中转圈,装好后显示"已安装",随 Ta 提供的显示"内置"。安装在离开页面后继续。
15
- - 点卡片进入详情页(`Esc` 或"返回"回到列表,滚动位置不变):头像、名称、说明、作者/版本/下载量/许可证/时间、安装或移除、npm/源代码/主页链接,`pi.video` / `pi.image` 预览,以及 README。
15
+ - 点卡片进入详情页(`Esc` 或"返回"回到列表,滚动位置不变):头像、名称、说明、作者/版本/下载量/许可证/时间、安装或移除、npm/源代码/主页链接,`pi.video` / `pi.image` 预览,以及 README。带 Web 扩展的包还有"打开":不安装,作为临时扩展直接运行它的页面(`pi.openTemporary`,见 [@celljs/ta-launcher](../ta-launcher/README.md)),之后在"快捷打开"里找到它。
16
+ - 免安装打开的临时扩展不列在"我的"里,由"快捷打开"安装或删除。
17
+ - 每一行和市场详情页都有"分享":打开 Ta 的分享弹窗(二维码、链接)。
18
+ - 快捷打开的搜索里加了"已安装""内置""市场"三个分区(`search.ts`,`registerSearch`):前两个在内存里过滤,市场经服务端搜 npm、分页,未安装的有"安装"按钮。
16
19
  - **服务端**(`pi.host`,`web-src/host.ts` → `host/index.mjs`):页面经 `callHost`(`TaPackageServer.callPackageHost`)调用。
17
20
  - `exportPackage(id)`:把包目录打成一个 `.tgz`(gzip 的 tar,顶层是包目录,去掉 `node_modules`、`.git` 和链接),用 base64 交给页面下载。和 `tar -czf <名字>.tgz <名字>` 的格式相同,没有 Ta 也能用 `tar` 解开。
18
21
  - `searchMarket(query, from?)`、`marketPackage(name)`(`market.ts`):在服务端查 npm,因为包也装在服务端;结果缓存 5 分钟,同一请求合并。搜索走 `/-/v1/search?text=<词> keywords:pi-package`;npm 对有关键词的搜索仍会把所有 `pi-package` 排在后面,所以只保留名称、说明或关键词里含有每个词的包,出现第一个不相关的就结束分页。详情不取 npm 的整份包文档(发版频繁的包有几十 MB),只取 `/<名字>/latest` 清单、上月下载量,README 先从 jsDelivr 取发布的那一版,没有再取 GitHub 仓库的;README 里的 HTML 图片、链接、标题转成 Markdown(Ta 的 Markdown 不渲染 HTML),去掉徽章,相对链接指向 GitHub 仓库。
package/host/index.mjs CHANGED
@@ -1,18 +1,18 @@
1
1
  // web-src/host.ts
2
- import { randomBytes } from "node:crypto";
3
- import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
4
- import { basename, dirname, join as join2 } from "node:path";
2
+ import { existsSync } from "node:fs";
3
+ import { basename as basename2, join as join2 } from "node:path";
5
4
 
6
- // web-src/archive.ts
7
- import { lstatSync, readdirSync, readFileSync } from "node:fs";
8
- import { join } from "node:path";
5
+ // ../ta-harness/esm/node/package-archive.js
6
+ import { randomBytes } from "node:crypto";
7
+ import { chmodSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
8
+ import { basename, dirname, join } from "node:path";
9
9
  import { gunzipSync, gzipSync } from "node:zlib";
10
10
  var BLOCK = 512;
11
11
  var LEFT_OUT = new Set(["node_modules", ".git", ".DS_Store"]);
12
- var ExtensionArchive;
13
- ((ExtensionArchive) => {
14
- ExtensionArchive.MAX_BYTES = 20 * 1024 * 1024;
15
- ExtensionArchive.MAX_FILES = 5000;
12
+ var PackageArchive;
13
+ (function(PackageArchive2) {
14
+ PackageArchive2.MAX_BYTES = 20 * 1024 * 1024;
15
+ PackageArchive2.MAX_FILES = 5000;
16
16
  function collect(root) {
17
17
  const files = [];
18
18
  let bytes = 0;
@@ -28,8 +28,8 @@ var ExtensionArchive;
28
28
  walk(file, path);
29
29
  } else if (stat.isFile()) {
30
30
  bytes += stat.size;
31
- if (files.length >= ExtensionArchive.MAX_FILES || bytes > ExtensionArchive.MAX_BYTES) {
32
- throw new Error(`The package in ${root} is larger than ${ExtensionArchive.MAX_FILES} files or ${ExtensionArchive.MAX_BYTES / 1024 / 1024} MB.`);
31
+ if (files.length >= PackageArchive2.MAX_FILES || bytes > PackageArchive2.MAX_BYTES) {
32
+ throw new Error(`The package in ${root} is larger than ${PackageArchive2.MAX_FILES} files or ${PackageArchive2.MAX_BYTES / 1024 / 1024} MB.`);
33
33
  }
34
34
  files.push({ path, data: readFileSync(file), executable: (stat.mode & 73) !== 0 });
35
35
  }
@@ -38,7 +38,42 @@ var ExtensionArchive;
38
38
  walk(root, "");
39
39
  return files;
40
40
  }
41
- ExtensionArchive.collect = collect;
41
+ PackageArchive2.collect = collect;
42
+ function extract(files, target) {
43
+ const staging = join(dirname(target), `.${basename(target)}.${randomBytes(4).toString("hex")}`);
44
+ try {
45
+ for (const file of files) {
46
+ const path = join(staging, ...file.path.split("/"));
47
+ mkdirSync(dirname(path), { recursive: true });
48
+ writeFileSync(path, file.data);
49
+ if (file.executable) {
50
+ chmodSync(path, 493);
51
+ }
52
+ }
53
+ rmSync(target, { recursive: true, force: true });
54
+ renameSync(staging, target);
55
+ } finally {
56
+ rmSync(staging, { recursive: true, force: true });
57
+ }
58
+ }
59
+ PackageArchive2.extract = extract;
60
+ function nameOf(files) {
61
+ var _a;
62
+ var _b;
63
+ const manifest = files.find((file) => file.path === "package.json");
64
+ try {
65
+ const name = (_a = JSON.parse(Buffer.from((_b = manifest === null || manifest === undefined ? undefined : manifest.data) !== null && _b !== undefined ? _b : []).toString("utf8"))) === null || _a === undefined ? undefined : _a.name;
66
+ return typeof name === "string" && name.trim() ? name.trim() : undefined;
67
+ } catch (_c) {
68
+ return;
69
+ }
70
+ }
71
+ PackageArchive2.nameOf = nameOf;
72
+ function directoryName(name) {
73
+ const plain = name.slice(name.lastIndexOf("/") + 1).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "");
74
+ return plain || "extension";
75
+ }
76
+ PackageArchive2.directoryName = directoryName;
42
77
  function pack(top, files, mtime = Date.now()) {
43
78
  const blocks = [header(`${top}/`, 0, 493, "5", mtime)];
44
79
  const directories = new Set;
@@ -57,12 +92,13 @@ var ExtensionArchive;
57
92
  blocks.push(new Uint8Array(BLOCK * 2));
58
93
  return gzipSync(Buffer.concat(blocks));
59
94
  }
60
- ExtensionArchive.pack = pack;
95
+ PackageArchive2.pack = pack;
61
96
  function unpack(archive) {
97
+ var _a;
62
98
  let tar;
63
99
  try {
64
- tar = gunzipSync(archive, { maxOutputLength: ExtensionArchive.MAX_BYTES + ExtensionArchive.MAX_FILES * BLOCK * 2 });
65
- } catch {
100
+ tar = gunzipSync(archive, { maxOutputLength: PackageArchive2.MAX_BYTES + PackageArchive2.MAX_FILES * BLOCK * 2 });
101
+ } catch (_b) {
66
102
  throw new Error("The file is not a .tgz of a package, or is larger than the limit.");
67
103
  }
68
104
  const files = [];
@@ -82,14 +118,14 @@ var ExtensionArchive;
82
118
  const body = tar.subarray(offset + BLOCK, offset + BLOCK + size);
83
119
  offset += BLOCK + size + padding(size);
84
120
  if (type === "x") {
85
- longPath = paxPath(body) ?? longPath;
121
+ longPath = (_a = paxPath(body)) !== null && _a !== undefined ? _a : longPath;
86
122
  continue;
87
123
  }
88
124
  if (type === "L") {
89
125
  longPath = text(body);
90
126
  continue;
91
127
  }
92
- const name = longPath ?? joinName(text(block.subarray(345, 500)), text(block.subarray(0, 100)));
128
+ const name = longPath !== null && longPath !== undefined ? longPath : joinName(text(block.subarray(345, 500)), text(block.subarray(0, 100)));
93
129
  longPath = undefined;
94
130
  if (type !== "0" && type !== "7" && type !== "5") {
95
131
  continue;
@@ -107,8 +143,8 @@ var ExtensionArchive;
107
143
  continue;
108
144
  }
109
145
  bytes += size;
110
- if (files.length >= ExtensionArchive.MAX_FILES || bytes > ExtensionArchive.MAX_BYTES) {
111
- throw new Error(`The package is larger than ${ExtensionArchive.MAX_FILES} files or ${ExtensionArchive.MAX_BYTES / 1024 / 1024} MB.`);
146
+ if (files.length >= PackageArchive2.MAX_FILES || bytes > PackageArchive2.MAX_BYTES) {
147
+ throw new Error(`The package is larger than ${PackageArchive2.MAX_FILES} files or ${PackageArchive2.MAX_BYTES / 1024 / 1024} MB.`);
112
148
  }
113
149
  files.push({ path: parts.slice(1).join("/"), data: new Uint8Array(body), executable: (octal(block.subarray(100, 108)) & 73) !== 0 });
114
150
  }
@@ -117,7 +153,7 @@ var ExtensionArchive;
117
153
  }
118
154
  return { top, files };
119
155
  }
120
- ExtensionArchive.unpack = unpack;
156
+ PackageArchive2.unpack = unpack;
121
157
  function header(path, size, mode, type, mtime) {
122
158
  const block = Buffer.alloc(BLOCK);
123
159
  const [prefix, name] = split(path);
@@ -192,7 +228,7 @@ var ExtensionArchive;
192
228
  function padding(size) {
193
229
  return (BLOCK - size % BLOCK) % BLOCK;
194
230
  }
195
- })(ExtensionArchive ||= {});
231
+ })(PackageArchive || (PackageArchive = {}));
196
232
 
197
233
  // web-src/market-util.ts
198
234
  var KIND_WORDS = {
@@ -517,15 +553,6 @@ class NpmMarket {
517
553
  }
518
554
 
519
555
  // web-src/host.ts
520
- var PackageFiles;
521
- ((PackageFiles) => {
522
- function directoryName(name) {
523
- const plain = name.slice(name.lastIndexOf("/") + 1).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "");
524
- return plain || "extension";
525
- }
526
- PackageFiles.directoryName = directoryName;
527
- })(PackageFiles ||= {});
528
-
529
556
  class ExtensionsService {
530
557
  host;
531
558
  market;
@@ -548,54 +575,30 @@ class ExtensionsService {
548
575
  if (pkg.origin === "builtin") {
549
576
  throw new Error(`${pkg.name} comes with Ta: everyone has it already.`);
550
577
  }
551
- const top = basename(pkg.root);
552
- const archive = ExtensionArchive.pack(top, ExtensionArchive.collect(pkg.root));
578
+ const top = basename2(pkg.root);
579
+ const archive = PackageArchive.pack(top, PackageArchive.collect(pkg.root));
553
580
  return { fileName: `${top}${pkg.version ? `-${pkg.version}` : ""}.tgz`, data: Buffer.from(archive).toString("base64") };
554
581
  }
555
582
  async importPackage(data, overwrite = false) {
556
583
  if (typeof data !== "string" || data === "") {
557
584
  throw new Error("Pass the bytes of the file in base64.");
558
585
  }
559
- const { top, files } = ExtensionArchive.unpack(Buffer.from(data, "base64"));
560
- const name = this.nameOf(files) ?? top;
561
- const directory = PackageFiles.directoryName(name);
586
+ const { top, files } = PackageArchive.unpack(Buffer.from(data, "base64"));
587
+ const name = PackageArchive.nameOf(files) ?? top;
588
+ const directory = PackageArchive.directoryName(name);
562
589
  const extensions = join2(this.host.agentDir, "extensions");
563
590
  const target = join2(extensions, directory);
564
591
  if (existsSync(target) && !overwrite) {
565
592
  return { status: "exists", name, directory };
566
593
  }
567
- const staging = join2(extensions, `.${directory}.${randomBytes(4).toString("hex")}`);
568
- try {
569
- for (const file of files) {
570
- const path = join2(staging, ...file.path.split("/"));
571
- mkdirSync(dirname(path), { recursive: true });
572
- writeFileSync(path, file.data);
573
- if (file.executable) {
574
- chmodSync(path, 493);
575
- }
576
- }
577
- rmSync(target, { recursive: true, force: true });
578
- renameSync(staging, target);
579
- } finally {
580
- rmSync(staging, { recursive: true, force: true });
581
- }
594
+ PackageArchive.extract(files, target);
582
595
  return { status: "imported", name, directory };
583
596
  }
584
- nameOf(files) {
585
- const manifest = files.find((file) => file.path === "package.json");
586
- try {
587
- const name = JSON.parse(Buffer.from(manifest?.data ?? []).toString("utf8"))?.name;
588
- return typeof name === "string" && name.trim() ? name.trim() : undefined;
589
- } catch {
590
- return;
591
- }
592
- }
593
597
  }
594
598
  function activate(host) {
595
599
  return new ExtensionsService(host);
596
600
  }
597
601
  export {
598
602
  activate as default,
599
- PackageFiles,
600
603
  ExtensionsService
601
604
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@celljs/ta-extensions",
3
- "version": "4.8.0",
3
+ "version": "4.9.1",
4
4
  "description": "A pi package for Ta: the page of extensions, where the user makes one by saying what it should do, and hands extensions on or takes them in as one file",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -18,7 +18,7 @@
18
18
  "web",
19
19
  "host",
20
20
  "skills",
21
- "web-src"
21
+ "!**/*.map"
22
22
  ],
23
23
  "scripts": {
24
24
  "build": "tsc -b && bun build web-src/index.tsx --format esm --target browser --outfile web/index.js && bun build web-src/host.ts --format esm --target node --outfile host/index.mjs",
@@ -27,14 +27,24 @@
27
27
  "watch": "tsc -b -w --preserveWatchOutput"
28
28
  },
29
29
  "devDependencies": {
30
- "@celljs/ta-protocol": "4.8.0",
31
- "@celljs/ta-web": "4.8.0",
30
+ "@celljs/ta-harness": "4.9.1",
31
+ "@celljs/ta-protocol": "4.9.1",
32
+ "@celljs/ta-web": "4.9.1",
32
33
  "@types/react": "^19.3.0"
33
34
  },
34
35
  "publishConfig": {
35
36
  "access": "public"
36
37
  },
37
38
  "pi": {
39
+ "title": {
40
+ "en": "Extensions page",
41
+ "zh-CN": "扩展页"
42
+ },
43
+ "summary": {
44
+ "en": "The Extensions page: ask Ta for a new extension in a sentence, import or export one, or install one from the market.",
45
+ "zh-CN": "导航栏里的\"扩展\"页:用一句话让 Ta 做扩展,导入、导出,或从市场安装。"
46
+ },
47
+ "icon": "Puzzle",
38
48
  "web": [
39
49
  "./web/index.js"
40
50
  ],
@@ -11,6 +11,8 @@ Ta is pi; what Ta can do grows with pi packages. A package can hold a pi extensi
11
11
 
12
12
  Put a new package in `~/.ta/agent/extensions/<name>/`, a lowercase name with dashes. pi loads the packages there by itself; there is nothing to install. Use `.ta/extensions/<name>/` of the project only when the user wants it for this project alone. To change a package, change its files in place. To remove one, delete its directory, after asking.
13
13
 
14
+ A small tool for now, which the user wants to use for a while rather than keep (a converter, a calculator, a board for one task), and which is only a page, goes in `~/.ta/agent/temporary/<name>/` instead: a temporary extension, as a mini program. It holds only a web extension (no pi extension, skills or prompts: those of a temporary package do not load) with one `page` view; it starts when the user opens it and is cleared after a while unused. Tell the user it is in Quick open (pulled down over the first tab of a phone, the grid at the bottom of the navigation elsewhere), where holding it keeps it in Mine or installs it. When in doubt, or when the user says to keep it, use `extensions/`.
15
+
14
16
  ```
15
17
  <name>/
16
18
  package.json {"name": "<name>", "version": "0.1.0", "type": "module", "pi": {"extensions": ["./index.ts"], "web": ["./web.js"]}}
@@ -18,7 +20,7 @@ Put a new package in `~/.ta/agent/extensions/<name>/`, a lowercase name with das
18
20
  web.js the web extension, if the package shows something on the web page
19
21
  ```
20
22
 
21
- List in `pi` only the parts that exist. The pi extension is an ordinary pi extension: read pi's extension documentation (its path is in your instructions) before writing one.
23
+ List in `pi` only the parts that exist. A web extension with only pages, used now and then, can start when one of them opens rather than with the page: `"webActivation": "open"` in `pi` (temporary ones always do); it is then in Quick open, not in the navigation, and what else it registers is there only while it runs. Also give `pi` what the user reads in the lists of extensions, in the user's language and English: `"title": {"en": "Timer", "zh-CN": "计时器"}`, `"summary"` (one sentence: what it does and where it shows), and `"icon"`, the name of one of `pi.ui.icons`. The pi extension is an ordinary pi extension: read pi's extension documentation (its path is in your instructions) before writing one.
22
24
 
23
25
  ## The web extension
24
26
 
@@ -43,13 +45,14 @@ export default function (pi) {
43
45
 
44
46
  - `React`: the React of the page. Use it for components and hooks; never bring another.
45
47
  - `ui.setWidget(key, Component, options?)`: a widget. `options.placement` is `'aboveEditor'` (default) or `'belowEditor'`, around the message box as in pi, or `'panel'`, a card in the cards tab of the workbench on the right (it opens when the first card comes): the place for what stays in view, like a timer or a list; `options.title` titles a card. `setWidget(key, undefined)` removes it.
46
- - `registerView(name, { title, render, icon?, location?, order?, head?, pages?, menu? })`: a view of its own; `render` is a component, `icon` a component that draws an icon of `size` pixels in `currentColor` (take one of `ui.icons`). `location: 'page'` (default) fills the main area, with an icon in the navigation on the left; `'sidebar'` is a tab at the top of the sidebar, beside the one of the chats (its icon is the tab), and fills the sidebar when picked; `'panel'` is a tool of the workbench beside the conversation, as the explorer or the terminal of an IDE: the workbench's `+` and its empty state list it, and it opens as one of its tabs. A `sidebar` or `panel` view gets a title and scrolling: render only the content. `order` sorts the views, smaller first (default 100). `head` is a component for the top bar in place of the title: for a `sidebar` view, the rest of the row right of the tabs (a search, a button to add), or the middle of a page's bar beside the menu and the workbench button. `pages`, on a `sidebar` view, lists the pages it leads to (ids `<package name>/<view name>`; `assistant/assistant` is the double): the navigation leaves them out. `menu`, on a page, returns its actions as sections of `{ key, label, icon?, disabled?, danger?, run }`; it is called each time the menu opens, and the sidebar view that lists the page draws it as a … on hover.
48
+ - `registerView(name, { title, render, icon?, location?, order?, head?, pages?, menu? })`: a view of its own; `render` is a component, `icon` a component that draws an icon of `size` pixels in `currentColor` (take one of `ui.icons`). `location: 'page'` (default) fills the main area, with an icon in the navigation on the left; `'sidebar'` is a list of the sidebar: its icon is at the top of the navigation, above the one of the chats (a tab at the bottom of a phone, before the chats), and it fills the sidebar when picked; `'panel'` is a tool of the workbench beside the conversation, as the explorer or the terminal of an IDE: the workbench's `+` and its empty state list it, and it opens as one of its tabs. `'board'` is a card of the board, which a phone brings out with a swipe to the left over its first tab (a button of the navigation elsewhere), for what is good to see at a glance (what runs, what is next): the user takes cards off, puts them back and orders them; render a few lines, no title. `'launcher'` is a section of Quick open, under Recent and Mine. A `sidebar` or `panel` view gets a title and scrolling: render only the content. `order` sorts the views, smaller first (default 100). `head` is a component for the top bar in place of the title: for a `sidebar` view, the row at the top of the sidebar (a search, a button to add), or the middle of a page's bar beside the menu and the workbench button. `pages`, on a `sidebar` view, lists the pages it leads to (ids `<package name>/<view name>`; `assistant/assistant` is the double): the navigation leaves them out. `menu`, on a page, returns its actions as sections of `{ key, label, icon?, disabled?, danger?, run }`; it is called each time the menu opens, and the sidebar view that lists the page draws it as a … on hover.
47
49
  - `registerMessageRenderer(customType, Component)`: shows the messages the pi extension sends with `pi.sendMessage({ customType, content, display: true, details })`; the component gets `{ message }`, `message.details` holds the data.
48
50
  - `registerTool({ name, description, parameters, execute(toolCallId, params) })`: a tool the model can call in the conversations the page opens, which runs in the browser; `parameters` is a JSON schema of an object; `execute` returns the text the model reads, or throws.
49
51
  - `registerOpener(link => boolean)`: opens what links of replies point to: `{ type: 'file', cwd, path, selection? }` (`selection` is `{ startLine, startColumn?, endLine?, endColumn? }`, from 1), `{ type: 'directory', cwd, path }` or `{ type: 'url', url }`; return `true` when it opened it, else the next opener is asked. @celljs/ta-workspace opens files, directories and pages already; register one only for links the package shows its own way.
52
+ - `registerComposerAddon({ actions?(conversation), above?, subscribe?(listener) })`: adds to the message box of every conversation (the double's, an agent's, any other): `actions` gives a section of entries of its + menu (`{ key, label, icon?, detail?, run() }`, or `items` for a list shown in its place, entries with `checked` and `group`); `above` is a component drawn above the box with `{ conversation }`; `subscribe` tells the boxes to read `actions` again. `conversation` is `{ sessionId, sessionFile?, cwd?, kind: 'double' | 'chat', group?, title? }`.
50
53
  - `on(type, handler)`: events of the conversation shown, as pi sends them (`agent_start`, `agent_end`, `message_end`, `tool_execution_end`, ...).
51
54
  - `sendUserMessage(text)`: sends a message to the conversation shown as if the user typed it; `'/name args'` runs a command of a pi extension.
52
- - `switchSession(sessionId)`: shows another open session of ta serve (an id of `server.listSessions()`) as the conversation; on a phone the drawer closes.
55
+ - `switchSession(sessionId, opening?)`: shows another open session of ta serve (an id of `server.listSessions()`) as the conversation; on a phone the drawer closes. Pass a promise of the id for a session still opening (`{ title, cwd }` in `opening` says what it is): it is in front at once, showing that it opens, so a click never waits on the server.
53
56
  - `reloadExtensions()`: after the extension installed, imported, turned on or off (`packages.setPackageEnabled(id, enabled)`) or removed a package itself (`packages.installPackage`, `packages.removePackage`), loads the web extensions and the pi extensions of the conversation again, as the end of a reply does. `packages.listPackages()` lists every package Ta loads, with what each holds.
54
57
  - `ui.notify(message, type?)`: a short notice; `type` is `'info'`, `'warning'` or `'error'`. `ui.confirm(title, message?, { confirmLabel?, danger? })` asks before going ahead and resolves with the answer; `danger` for what cannot be undone.
55
58
  - `ui.input(title, placeholder?, { value? })` and `ui.editor(title, prefill?)`: ask for one line or several, as pi's; they resolve with the text, or `undefined` when the user cancelled.
@@ -58,20 +61,21 @@ export default function (pi) {
58
61
  - `ui.createTerminal({ cols?, rows?, cwd? })`: a terminal as VS Code's (xterm.js on WebGL, in the page's theme), loaded the first time one is made; URLs and paths of files in it (`src/a.ts:10:5`) open with Cmd or Ctrl + click, paths from `cwd` or the directory the shell reports (OSC 7): `write(data)` the program's output, `onData(listener)` what the user types, `onResize(listener)` its new size in characters, `attach(element)` shows it in an element with a size and `position: relative` (returns the function that takes it out; it keeps its screen meanwhile), `focus()`, `dispose()`. `pi.terminals` runs a shell of the server behind it.
59
62
  - `ui.useCwd()`: a React hook, the directory of the conversation shown. `ui.useSessionId()`: the session of the conversation shown.
60
63
  - `ui.showView(id)`: shows a view of any extension by its id, a page in the main area or a workbench tool as its tab; `''` shows the conversation again. `ui.useView(id)`: a React hook, `{ title, location, shown, menu? }` while that view is loaded, else `undefined`.
61
- - `ui.Composer`: the message box of every conversation, `{ placeholder?, onSend(text), mentions?, mentionLabel?, actions? }`: `mentions` (`{ name, detail? }[]`) is what `@` lists; `actions` are sections of its + menu, entries `{ key, label, icon?, detail?, insert? | run() }` (`insert` puts text at the caret). Use it for any conversation an extension shows, rather than a box of its own. `ui.Markdown` (`{ text }`) renders messages as the conversations do. `ui.Dialog` (`{ title, onClose, children }`) is a dialog over the whole page, as Ta's own: use it to make or change things rather than a form in a sidebar.
64
+ - `ui.Composer`: the message box of every conversation, `{ placeholder?, onSend(text), mentions?, mentionLabel?, actions? }`: `mentions` (`{ name, detail? }[]`) is what `@` lists; `actions` are sections of its + menu, entries `{ key, label, icon?, detail?, insert? | run() }` (`insert` puts text at the caret). Use it for any conversation an extension shows, rather than a box of its own. `ui.Markdown` (`{ text }`) renders messages as the conversations do. `ui.Empty` (`{ title, hint?, compact?, tone?, picture?, children? }`) is what an empty list or view shows, as Ta's own lists: a short title without a full stop, at most one quieter hint, centered in its parent (a column of flex); `compact` in a menu, picker or dialog; `picture` above it where seeing what will be there helps (a first page, a list the user fills). Use it rather than text of your own. `ui.Picture` (`{ width?, height?, frame?, className?, children }`, 160 by 96 in a rounded frame unless told) is a small picture as Ta's own: draw a few `rect`, `circle`, `path` and `text` in it with the classes `ta-pic-pane` (a surface), `ta-pic-line` (a bar of text), `ta-pic-box` (an outline), `ta-pic-accent` (what it is about), `ta-pic-mark` (green), `ta-pic-soft` (half of it), `ta-pic-dot`, `ta-pic-bad` (red), `ta-pic-path` (a dashed way), `ta-pic-stroke` (a green line), `ta-pic-tick` (a line on green) and `ta-pic-text` (code), never colors of your own, so it follows the theme. `ui.PictureCards` (`{ cards, columns?, compactColumns? }`, cards `{ key, picture, label, hint?, title?, disabled?, onPick() }`) is a row of them to pick from, as the suggestions of an empty conversation. `ui.Dialog` (`{ title, onClose, children }`) is a dialog over the whole page, as Ta's own: use it to make or change things rather than a form in a sidebar.
65
+ - `ui.usePages()`: a React hook, every page there is (`{ id, extension, title, icon?, state, onOpen, place, usedAt?, source?, temporary? }`), what Quick open lists; `ui.stopExtension(name)` stops one that started on open, `ui.forgetPage(id)` takes one out of Recent. `openTemporary(source, 'link')` opens a package of npm or Git without installing it and shows its first page: ask the user first. `ui.useContextMenu()`: a React hook, `[menu, open]`: render `menu`, and call `open(event, sections)` from `onContextMenu` (a long press on a touch screen is one), sections of `{ key, label, icon?, disabled?, danger?, run }`. `ui.shareExtension({ title, source?, packageId? })` opens Ta's dialog that shares an extension (a link and its QR code), `ui.openShared(text)` opens such a link after asking, and `registerSearch({ key, title, order?, remote?, search(query, offset), subscribe? })` adds a section to the search of Quick open (entries `{ key, title, detail?, icon?, tint?, action?, open(), menu? }`). `ui.QrCode` (`{ text }`) draws a QR code; `ui.scanCode?.(instructions)`, only in the Ta app, scans one with the camera.
62
66
  - `ui.Avatar`: Ta's avatar, the Cell logo, as a component `{ size?, mood?, mark? }`; `mark`, one or two characters, tells agents apart. Use it wherever Ta speaks, and draw Ta no other way.
63
67
  - `ui.icons`: the lucide icons of the page by name (`Plus`, `Hash`, `Search`, `Files`, ...): a web extension cannot import them. Check for one before using it: the list only grows.
64
68
  - `storage.get(key)` and `storage.set(key, value)`: small JSON values kept on the server for the package, so they stay across browsers and devices; setting `null` removes a key. A package keeps at most 4 MB there. `storage.onChange(keys => ...)` hears keys changed by other pages or the server. `storage.directory(cwd)` has the same methods for values of one directory (use `ui.useCwd()`), such as the folders open in a tree: keep there what belongs to a directory, and in `storage` what belongs to the user.
65
69
  - `ui.theme` (`'light'` or `'dark'`) and `ui.language` (`'zh-CN'` or `'en-US'`): write the words of the extension in the language of the page.
66
- - The services of ta serve, for what the rest cannot do, all on its one connection: `server` (sessions: the commands of pi's RPC mode, `listSessions`, `openSession`, `prompt`, ...), `workspace` (files and programs of a directory: `listDirectory`, `readFile`, `writeFile`, `fileUrl`, `findFiles`, `runCommand`), `terminals` (`openTerminal`, `writeTerminal`, ...; output by `onTerminalData`) and `packages` (`listPackages`, `installPackage`, `removePackage`).
70
+ - The services of ta serve, for what the rest cannot do, all on its one connection: `server` (sessions: the commands of pi's RPC mode, `listSessions`, `openSession`, `prompt`, ...), `workspace` (files and programs of a directory: `listDirectory`, `readFile`, `writeFile`, `fileUrl`, `findFiles`, `runCommand`), `terminals` (`openTerminal`, `writeTerminal`, ...; output by `onTerminalData`) and `packages` (`listPackages`, `installPackage`, `removePackage`, and for temporary packages `openTemporaryPackage`, `updateTemporaryPackage`, `installTemporaryPackage`).
67
71
 
68
- Look like the page: inherit its font, and use its colors through CSS variables, which follow the light and dark theme: `var(--ta-text)`, `var(--ta-secondary)`, `var(--ta-muted)`, `var(--ta-card)`, `var(--ta-raised)`, `var(--ta-border)`, `var(--ta-accent)`, `var(--ta-red)`. Radius 8px for controls. Keep data the extension must remember with `pi.storage`; `localStorage` only for what belongs to one browser, under keys that start with the package name.
72
+ Look like the page: inherit its font, and use its colors through CSS variables, which follow the light and dark theme: `var(--ta-text)`, `var(--ta-secondary)`, `var(--ta-muted)`, `var(--ta-card)`, `var(--ta-raised)`, `var(--ta-border)`, `var(--ta-accent)`, `var(--ta-red)`. Radius 8px for controls. Write a font size in px as `calc(13px * var(--ta-font-scale))` (a line height in px too), so that it follows the font size of the settings; the messages of a conversation and its field carry the class `ta-conversation`, which adds the font size of conversations. Keep data the extension must remember with `pi.storage`; `localStorage` only for what belongs to one browser, under keys that start with the package name.
69
73
 
70
74
  The two halves talk through the conversation: the web extension sends `/command args` with `sendUserMessage`; the pi extension answers with `pi.sendMessage` and a `customType` the web extension renders.
71
75
 
72
76
  ## Packages that come with Ta
73
77
 
74
- Ta comes with some packages of its own, which are on until the user turns them off in Settings → Extensions: `@celljs/ta-workspace` (the explorer, search, source control, terminals and browser beside the conversation), `@celljs/ta-channels` (agents and channels), `@celljs/ta-computer-use` (desktop apps through Cua Driver), `@celljs/ta-changes` (the files each reply changed, their diffs, and undo), `@celljs/ta-cron` (prompts that run on a schedule, with the Scheduled page, `/loop`, `/remind`, `/schedule` and the tool `schedule_task`), `@celljs/ta-agents` (other coding agents such as CodeBuddy Code, Claude Code and Codex as models) and `@celljs/ta-extensions` (this skill, and the Extensions page in the navigation, which lists the user's packages to change, export or remove and imports others). Do not copy or change them; build a new package for something new. The web page calls packages "extensions": use that word with the user.
78
+ Ta comes with some packages of its own, which are on until the user turns them off in Settings → Extensions: `@celljs/ta-workspace` (the explorer, search, source control, terminals and browser beside the conversation), `@celljs/ta-channels` (agents and channels), `@celljs/ta-computer-use` (desktop apps through Cua Driver), `@celljs/ta-changes` (the files each reply changed, their diffs, and undo), `@celljs/ta-cron` (prompts that run on a schedule, with the Scheduled page, `/loop`, `/remind`, `/schedule` and the tool `schedule_task`), `@celljs/ta-bots` (bots of WeChat and WeCom connected to the double, an agent or a conversation, with the tool `bot_send_file`), `@celljs/ta-agents` (other coding agents such as CodeBuddy Code, Claude Code and Codex as models), `@celljs/ta-launcher` (Quick open: Recent and Mine, and links of extensions opened without installing) and `@celljs/ta-extensions` (this skill, and the Extensions page in the navigation, which lists the user's packages to change, export or remove and imports others). Do not copy or change them; build a new package for something new. The web page calls packages "extensions": use that word with the user.
75
79
 
76
80
  Under `ta serve`, with `@celljs/ta-channels` on, you have tools to build a team for what the user wants: `create_agent` (a name and a role: another Ta with its own session), `create_channel` (agents, the lead first), `add_to_channel` (agents that exist, after the members; the lead stays), `post_to_channel` (a message; the agents it names with @ answer, or the lead, and they may hand on a few times) and `list_channels`. The agents run in ta serve, so they go on when the page closes. When the user asks for a team, for roles working together or for a review by several hands, create the agents and the channel and post the goal; do not write a package for it. In `ta` without `serve` the tools say they need `ta serve`: tell the user so.
77
81
 
@@ -88,4 +92,4 @@ A package travels as one `.tgz` file: a gzipped tar of its directory, the direct
88
92
 
89
93
  1. `node --check web.js` and, for the pi extension, read it once more against pi's documentation.
90
94
  2. When your reply on the web page ends, the page loads new and changed web extensions and their tools, and reloads the pi extensions of its conversation. Otherwise the page loads them when it is shown again, and `/reload` reloads pi extensions in the terminal. Do not ask the user to restart anything.
91
- 3. Tell the user in one or two sentences what the package does and where it shows. No file listings unless asked.
95
+ 3. Tell the user in one or two sentences what the package does and where it shows. No file listings unless asked.